Conventions for the Design Chapters of the Course

We have made a concerted effort to ensure that all of our lessons are easy to understand. However, before reading through the design portion of the course, we consider it necessary to explain some conventions used in the coming chapters that will make it easy to understand different design decisions.

Conventions#

We have listed each convention briefly below:

• We assume you’ve read through the course in the order it’s presented in. However, we have tried our best to decouple each of the four design problems. The prerequisite concepts you should be familiar with in order to complete a design problem are hyperlinked within the corresponding design problem lessons.

• Most of the public-facing APIs use REST architecture. Therefore, our course uses the convention of following the same architecture.

• Most well-known applications, like Twitter, Messenger, Google Maps, etc., have numerous features that require complex and rich API endpoints. Since we can't cover all the features in our API designs, we focus on the most interesting aspects of the API. Therefore, our design decisions and protocol selection is impacted accordingly.

• Our design consideration lessons choose various architectural styles, communication protocols, and data formats for design problems that best suit our functional requirements. Though we decide to use a certain set of architectural styles and protocols, it’s possible to implement the same system using a different set of architectural styles and protocols. Take the example of Khan Academy, which started with REST architectural style but later migrated to GraphQL.

• While it's possible to use multiple versions of HTTP within the same application, which is an industry practice, we choose one version of HTTP that we believe fulfills the larger part of the functional requirements for the design problem at hand. We assume that our APIs will use HTTP/1.1 or above. Generally, newer versions of HTTP are backward compatible. However, HTTP/3.0 is partially compatible but is still being worked on to reduce the impact of the transition from HTTP/2.0 to HTTP/3.0.

• There can be multiple endpoints for a service. Many endpoints help us perform load balancing and filtering at the API gateway level. The API gateway is more like a layer-7 switch, where, for example, it can route different endpoint traffic to various places in the data center. We use the map illustration below to represent the endpoints of an API, where a learner can click on a filled circle to expand endpoints in case it is not expanded.For example, the red circle in the illustration below represents the "Update comment" endpoint. We can see the operations, such as create, update, read a comment, etc., that a specific endpoint intends to perform on the backend are defined. Each operation is performed by interacting with the defined endpoint, which can be the same or different depending on the service. The {params} parameter indicates that the user's variables, such as commentID or other variables will be parsed to interact with the relevant endpoint.

• We use code-like snippets instead of executable code in the various design lessons in the course. These snippets give you an idea of how requests and responses will look and what values different HTTP headers can have to make an API call. We include both HTTP and cURL request formats. The focus of the course is to help you learn to design, not implement or execute. For example, the code below shows the request and response message format for creating a new comment.

• Some of the content in the design problems used in these lessons may feel repetitive—for instance, the error responses from different APIs. While we want to avoid repetition, it may not be possible because certain error codes and corresponding responses are custom to specific APIs. You may skim over them if you don't find them relevant.

• We define the data entities exchanged between the clients and servers for a design problem in a single placeholder. Alternatively, we could use data entities on the basis of an endpoint. However, this would take a lot of space and divert us from the main goal of covering different important aspects of the request and response messages endpoint. For example, here is a sample of data entities for designing a comment system:

• Note that the URLs, URIs, and data entities mentioned in the design chapters of the course are hypothetical.

In this lesson, we presented our design problem conventions upfront so that we are on the same page for efficient learning. We have outlined these conventions to set your expectations about what lies ahead in the course.